Software 2000

home *** CD-ROM | disk | FTP | other *** search

/ Software 2000 / Software 2000 Volume 1 (Disc 1 of 2).iso / utilities / u136.dms / in.adf / TEXTRA / Textra.DOC.pp / Textra.DOC

Wrap

Text File | 1978-08-30 | 23.9 KB | 561 lines

This document describes Textra, a very user-friendly text editor. Textra makes no claim at being the most powerful editor around, or the fastest, smallest or any-OTHER-est. Just pretty easy to use, that's the goal. And free. Textra is FreeWare. I request, however, that this README file accompany the executable if passed around. Textra was written in JForth Professional V2.0, which I recommend highly. Thanx, Mike Haas. 26-Apr-89 executable size 60148 29-May-89 " " " 60864 22-Jul-89 " " " 61080 21-Oct-89 " " " 65208 05-Jan-90 " " " 69836 18-Feb-90 " " " 69400 --------------------------------------------------------------------------- T A B L E O F C O N T E N T S --------------------------------------- 1. INVOKING TEXTRA 1.1 Invoking from Workbench or CLI 1.2 Optional filename argument usage 1.3 Shift-Double-clicking with "project"-type icons 1.4 Textra as the Default Tool for "Project"-type icons 2. THE TEXTRA CURSOR 2.1 Cursor appearance 2.2 Positioning the cursor with the keyboard arrow keys 2.3 Positioning the cursor with the mouse 2.4 Quickly finding the cursor (function key F3) 3. ENTERING TEXT INTO THE DOCUMENT 3.1 Inserting text at the cursor location 3.2 The RETURN key 3.2.1 The "Auto-Indent" mode 3.3 The BACKSPACE key 3.3.1 The "Auto-BackSpace" mode 3.4 The DEL key 3.5 The TAB key 3.5.1 Settable TAB Width 3.6 The control-key filter and defeat feature (Function key F2) 4. SELECTING A RANGE OF TEXT 4.1 Using the mouse to select a range of characters 4.2 Selecting text by double-clicking 4.3 Operations on selected ranges 4.4 Selecting more than the visible screen 4.5 Quickly finding the selected range (function key F3) 4.6 Extending a select range by SHIFT-clicking 5. VIEWING PAGES 5.1 The vertical scroll arrow gadgets 5.2 The vertical scroll thumb gadget 5.3 Scrolling the page with the keyboard arrow keys 5.4 Keys that PAGE-up or PAGE-down 6. TEXTRA WINDOWS 6.1 Limitations 6.2 The title bar 6.3 The close gadget 6.3 The sizing gadget 6.4 The Window-Size-Toggle feature (Function key F1) 7. TEXTRA MENUS 7.1 Accessing the menus 7.2 The "Project" menu 7.2.1 Open A File... 7.2.2 Open By Name... 7.2.3 New File 7.2.4 Revert To Saved 7.2.5 Save File 7.2.6 Save File As... 7.2.7 Save All Files 7.2.8 Close File 7.2.9 About Textra... 7.2.10 Quit 7.3 The "Edit" menu 7.3.1 Cut 7.3.2 Copy 7.3.3 Paste 7.3.4 Find 7.3.4.1 String... 7.3.4.2 Next Occurence 7.3.5 Replace 7.3.5.1 String... 7.3.5.2 Next Occurence 7.3.6 Case 7.3.6.1 lower 7.3.6.2 UPPER 7.3.6.3 Capitalize 7.3.7 Go to Line... 7.3.8 Preferences... 7.4 The "Windows" menu 7.4.1 Dynamically-changing items 7.4.2 Additional information 8. TEXTRA GENERAL INFORMATION 8.1 Textra's use of Path and File names 8.2 String Gadget Shortcuts 8.3 Textra String Gadgets and the RETURN key 8.4 Textra Requesters 8.5 Textra Keyboard Summary --------------------------------------------------------------------------- 1. INVOKING TEXTRA 1.1 Textra, if double-clicked from WorkBench, will ask you to select a filename soon after opening its first window. Textra may be launched from CLI or SHELL with multiple filenames as follows: 1> TEXTRA <filename1> <filename2> ... <filenameX> OR 1> RUN TEXTRA <filename1> <filename2> ... <filenameX> 1.2 If the optional filenames are not given, Textra will ask you to select one, as if double-clicked. Select "CANCEL" if you do not want to edit an existing file; the default name "Untitled" will be assigned. 1.3 From Workbench, "Project" icons that are also selected when Textra is "SHIFT-Double-Clicked" will each be opened in their respective window. 1.4 A "Project" icon that has Textra specified in its "Default Tool" field will invoke Textra, when double-clicked, and be opened in its own window. --------------------------------------------------------------------------- 2. THE TEXTRA CURSOR 2.1 The current cursor location (where text will be inserted) is represented by a thin line, of a different color than either text or background. If placed inside a text string, the cursor is always BETWEEN two characters, showing clearly the sections that will "spread apart" if something is typed into the window. 2.2 The cursor may be moved with the "arrow" keys on the keyboard; a SHIFT-left-arrow or SHIFT-right-arrow will move the cursor to the beginning or end of the current line, respectively. 2.3 The cursor may also be positioned by clicking the LEFT MOUSE BUTTON, while the mouse cursor is over a part of the windows text area. 2.4 The display will move to the cursor location when the F3 key is pressed. --------------------------------------------------------------------------- 3. ENTERING TEXT INTO THE DOCUMENT 3.1 As keys are typed at the keyboard, they are entered in the file at the current cursor location, and the cursor is advanced by one. 3.2 The RETURN key inserts a new line, and moves the cursor there. 3.2.1 If the Auto-Indent mode is enabled (see section 7.3.8), the cursor will advance to the same column as the 1st non-blank character on the line above when the RETURN key is pressed. 3.3 The BACKSPACE deletes the character to the immediate left of the cursor and backs the cursor up one column. If the cursor is at the leftmost column, the preceeding newline is removed and the cursor moves up one line. 3.3.1 The Auto-BackSpace mode (section 7.3.8), if enabled, comes into play when the cursor rests on the 1st non-blank character of a line. Then, the line is "backed-up" by whatever it takes to line up with the beginning of the text on the line above. If the previous line does not start to the left of the cursor line, the alignment is made to the next line above that does. 3.4 The DELETE key removes the character to the immediate right of the cursor. If the cursor is at the end of a line, the newline is removed and the next line moves up to merge with the current. 3.5 The TAB key advances the cursor to the next column that is an even multiple of the TAB width value (section 3.5.1). 3.5.1 Settable TAB WIDTH (section 7.3.8) provides a way of changing the default TAB width (8). A string requester is presented, with the currently installed size. Maximum width accepted is 16. The setting applies to all windows. 3.6 Normally, Textra will not allow control characters into the window, permitting only visible or white-space characters. This feature can be temporarily defeated, for 1 character, by pressing F2. Following F2, the next character will be accepted into the window unfiltered. --------------------------------------------------------------------------- 4. SELECTING A RANGE OF TEXT 4.1 It is possible to mark a series of characters for the next operation by "dragging" with the mouse. The sequence is: a. Position the mouse over the 1st character of the desired series. b. Press the left mouse button and, while holding it down, move the mouse to the last character of the series (even if it is on another line). Note that the characters between that clicked-on and wherever you move the mouse become "highlighted" (selected). c. Release the left mouse button when the desired range of characters is selected. 4.2 Any series of non-white characters will become selected if the LEFT MOUSE BUTTON is double-clicked while the mouse cursor is positioned over them. 4.3 When a range of text is selected, a subsequent operation will affect the entire selected area. For example, if a key is typed while a range is selected, the range will be cut from the file, replaced by that key. Other examples are the BACKSPACE and DEL keys, which both act to simply delete any selected area. Certain items under the EDIT menu, described later, also operate on any current range. 4.4 If, while selecting text, the mouse is moved near the bottom or top of the window, available text in the appropriate direction will scroll into view, becoming selected in the process. Therefore, a select range can extend past the visible limits of the window. 4.5 The display will move to the beginning of any currently-selected range when the F3 key is pressed. 4.6 A select range may be established or size changed by holding down the SHIFT key when clicking in the window. If the click occurs outside the current select range, the range is extended to there. If inside, the end-point of the select range is adjusted to the click-point. --------------------------------------------------------------------------- 5. VIEWING PAGES 5.1 The easiest method for moving through the file is to use the vertical scroll bar on the right side of the window. Single clicks of the left mouse button on the arrows at either end move the document vertically, one line at a time. Holding the left button down on either yields a continuous scroll. 5.2 The "thumb" in the middle of the scroll bar not only indicates the visible-page-area relative to the total-file-size (by it's height), but also the position within the file (by its vertical positioning). It can also be "selected" with the left mouse button and moved as a "coarse adjust". The area immediately above and below the "thumb" may be clicked with the left button as a "page-scroll" mechanism. 5.3 Another method by which text may be scrolled into view is to move the cursor, via the keyboard "arrow" keys, to either the top or bottom of the visible window. Attempts to move the cursor "off the window" will cause text in that direction to scroll. 5.4 Function keys F4 and F5 will PAGE the display down and up, respectively. The Shift-arrow-key combinations will also PAGE the display in the appropriate direction AND position the cursor to the middle of the new page. --------------------------------------------------------------------------- 6. TEXTRA WINDOWS 6.1 Textra allows any number of windows, limited by the amount of memory in your computer (most limiting is probably the amount of available CHIP ram). Textra lines can be up to 255 characters long, number of lines limited by your total available memory (entire file is kept in ram, FAST is grabbed first). 6.2 The title of each Textra window is set to the full-pathname of the file that was read in (or created). This is also the name of the file that will be written during a SAVE operation (unless the "SAVE AS..." menu option is chosen, section 7.2.6). If the file has been modified since last saved, the filename will be preceeded by a '*'. 6.3 Each window includes a standard Intuition close gadget, which performs the same action as the "CLOSE FILE" menu option. See the discussion on "CLOSE FILE" (section 7.2.8) for more information. 6.4 The "sizing" gadget in the lower-right hand corner of each window may be used to adjust the dimensions of that window, up to the full-screen limitations of the Workbench. 6.5 Function key F1 may be used as a "window-size-toggle" between default size (when F1 was first hit) and full-screen (as per current screen resolution settings). This is particularly useful when Workbench is in 400 line interlace. (NOTE: if F1 is used to expand the screen, and the size gadget is then clicked without actually changing size, the default-size becomes equal to the full-screen-size. This will make F1 non-functional until the size gadget is used to actually change window size. To avoid this, don't click on the sizing gadget when the window is full-size. Use F1 to get back to normal size). --------------------------------------------------------------------------- 7. TEXTRA MENUS 7.1 3 menus are available and present themselves when the RIGHT MENU BUTTON is depressed and held. Some menu items may also be activated by simultaneously pressing the RIGHT AMIGA key and the one that is specified in the menu item text. 7.2 The "Project" Menu 7.2.1 OPEN A FILE... opens a new window with a full file-selector requester and buttons that allow quick access to the top 6 disk devices (like DF0:). The PARENT button changes the current directory to the level above the one being displayed. The KEYBOARD button presents the user with a string requester into which a file or directory specification may be typed. The CANCEL button exits the requester with no other action while the OK button enters the file or directory selected in the list box (the same as CANCEL if nothing is selected). Double-clicking one of the names performs the same action as the OK button. 7.2.2 OPEN BY NAME... opens a new window, then presents a string requester for specifying a filename (directory names are invalid in this requester) from the keyboard. This bypasses the directory scan for the list of names, which can take time on large directories, especially on floppy drives. Note that the current directory of the requester is that of the spawning window. 7.2.3 NEW FILE opens a window without specifying a filename; the default name "Untitled" is assigned, at the directory level of the spawning window. 7.2.4 REVERT TO SAVED causes the read-in version of the selected file to be discarded, replaced by the version that was last-saved to disk. A verification requester is presented to make sure this is not done accidently. 7.2.5 SAVE FILE causes the currently-selected file to be written to disk, if modified. If the file has not been changed (no '*' before the title), this menu item is disabled. 7.2.6 SAVE FILE AS... allows saving the currently selected file under a different name. After this operation, the title bar will contain the new name, and it will have been created on disk. If the specified file already exists, the user is warned and given a chance to abort. The "USE LIST" button will present a full file-requester through which an existing file may be selected with the mouse. This requester is very similar in operation to the "OPEN FILE..." requester; all buttons work the same, except the OK button will overwrite the selected file (as does double-clicking a filename). 7.2.7 SAVE ALL FILES causes all files that have been modified and not saved to be written to disk. If there are no modified files, this menu item is disabled. 7.2.8 CLOSE FILE will check if the file has been modified but not saved and warn the user if so. Note that closing Textra's last window will cause it to exit; a requester will notify you if you are closing the last window and give you the chance to abort. 7.2.9 ABOUT TEXTRA is self-explanatory. 7.2.10 QUIT will exit Textra, closing all files in the process. All files that have been modified but not saved will issue a notification requester, providing the opportunity to save at that time. 7.3 The "Edit" Menu 7.3.1 CUT removes the selected range of characters from the currently-selected file, but saves them in the Textra clip area (Textra does not interface with the standard Amiga Clipboard Device...future versions may do so). The previous contents of the Textra clip area are lost. If there is no select range, this menu item is disabled. 7.3.2 COPY moves the selected range of characters of the currently-selected file to the Textra clip area, but does not remove them from the file. The previous contents of the Textra clip area are lost. If there is no select range, this menu item is disabled. 7.3.3 PASTE inserts whatever is in the Textra clip area into the currently-selected file, at the current cursor location. If a select range is active in this file, it is deleted before the insertion takes place. There is no effect on the contents of the Textra clip area. It nothing has been placed into the Textra clip area (via CUT or COPY), this menu item is disabled. 7.3.4 FIND presents a sub-menu with 2 choices: 7.3.4.1 STRING... presents a requester prompting for the string to search for, ignoring character case. The string gadget will, as a default, contain the previous string searched for IN THAT WINDOW (empty if none). However, if a range of characters is selected that is ALL ON ONE LINE, it will supercede any previously-searched-for string as the default for the string gadget. The search begins just past the current cursor location or selected range of characters. 7.3.4.2 NEXT OCCURENCE conducts another case-insensitive search for the same text string that had previously been searched for. If no search had yet been conducted the "STRING..." requester is presented. 7.3.5 REPLACE presents a sub-menu with 2 choices: 7.3.5.1 STRING... presents a double-string-requester, prompting for both the string to conduct a case-insensitive search for, and a second string, to replace the first with, when found. The RETURN key will toggle the selected string gadget. The user may optionally replace all instances of the found string (with the "ALL!" button), just the next one found (via the "ONCE" button), or abort (via "CANCEL"). The search begins just past the current cursor location or selected range of characters. 7.3.5.2 NEXT OCCURENCE conducts another "REPLACE" operation, using the same strings that were used last time. If none exist, the "STRING..." requester is presented. 7.3.6 CASE presents a sub-menu with 3 choices: 7.3.6.1 LOWER exhibits 2 behaviors depending on whether an area is selected or not. If there is, the entire selected area is converted to lower case. If not, the next word after the cursor is searched for and converted to lower case if found. 7.3.6.2 UPPER exhibits 2 behaviors depending on whether an area is selected or not. If there is, the entire selected area is converted to upper case. If not, the next word after the cursor is searched for and converted to upper case if found. 7.3.6.3 CAPITALIZE exhibits 2 behaviors depending on whether an area is selected or not. If there is, each word in the selected area is located and capitalized. If not, the next word after the cursor is located and capitalized. 7.3.7 GO TO LINE... presents a string requester prompting for the desired line number, with the initial string gadget contents being equal to the current cursor line (or the beginning of any selected range). First line of file is considered line 1. 7.3.8 PREFERENCES... presents a requester allowing the selection of modes and settings, specifically, the "Auto-Indent" mode (section 3.2.1), the "Auto-BackSpace" mode (section 3.3.1) and the TAB WIDTH (section 3.5.1). The USE button causes the currently displayed settings to go into effect. The USE+SAVE button does the USE function, and also saves the current settings in a file called "Textra.prefs". This file is written to the Textra "startup directory". This is the directory that was either current if Textra was invoked from CLI, or the one that contained Textra if double-clicked from Workbench. The CANCEL button causes any currently displayed settings that have been changed, to be discarded. If the PREFERENCES requester is active, this menu item is disabled. 7.4 The "Windows" Menu 7.4.1 One item exists in the "WINDOWS" menu for each open file, the menu item text being the same as the title bar for the associated window. Selecting an item makes it the current window, if not already. 7.4.2 Additionally, the text includes the "*" character before the filename if the file has been modified since last written to disk. A checkmark preceeds the item representing the current file. --------------------------------------------------------------------------- 8. TEXTRA GENERAL INFORMATION 8.1 Textra always fully expands a specified file or directory name and uses that form to again find the file, if necessary. For example, you may have typed in "DF1:MyFile" as the filename, but the window title will substitute the name of the volume, possibly "MyDisk:MyFile". This is almost always desirable, because if Textra saved "DF1:", you might unknowingly save it to the wrong disk, just because you switched the disk in that drive. Textra will ask you specifically for the same name. The only situation you should be aware of is WHEN YOU HAVE TWO DISKS OF THE SAME NAME in your system. In this case, AmigaDOS can sometimes choose the wrong disk when Textra passes the full-pathname to it. In the above example, we could save it to the wrong disk if the disk in DF0: is also named "MyDisk:" (a backup, perhaps???). This is not caused by Textra, but can happen anytime in AmigaDOS that you use the full-pathname to specify a file. 8.2 Intuition provides two String Gadget shortcuts that can be useful to the Textra user. Textra string gadgets that provide a default text string when they appear will revert back to this string whenever "Right Amiga-Q" is pressed. The "Right Amiga-X" combination will clear any displayed string. 8.3 For all string gadgets but one, the RETURN key will perform the same action as the "OK" button. The one exception is the "REPLACE" double-string requester, where the RETURN key toggles between the two string gadgets. 8.4 Textra Requesters are attached to (drawn in) the window that they have been spawned from. The advantage is that multiple requesters are possible...you can select and work in another file even if the previous window is waiting for you to answer a question. Every window can, in fact, have an open requester. Note that, if your window is too small, you may have to expand its size to inter-operate with a given requester. Unfortunately, since the Intuition requester mechanism locks out my console events from that window, I can't process the F1 key, and you have to do this with the mouse. (Intuition should give the application a looksee at the keys before using them in a string gadget, throwing them away or whatever. The application could reply with a boolean, whether it wants the requester to use it or not. This could even default to NO_BOOLEAN if not specified previously by the caller as a requester mode. Maybe a REQ_KEY_VERIFY event. Oh well, let's re-design Intuition another time). 8.5 Keyboard Summary: F1 - Window Size Toggle (6.4) F2 - Keyboard Filter Defeat (3.6) F3 - Page to Cursor or Beginning of Select Range (4.5) F4 - Display next page (5.4) F5 - Display previous page (5.4) Shift-Left-arrow - Cursor to beginning of current line (2.2) Shift-Right-arrow - Cursor to end of current line (2.2) Shift-Up-arrow - Display previous page, cursor to middle (5.4) Shift-Down-arrow - Display next page, cursor to middle (5.4) Right-Amiga-O - Open existing file via file requester (7.2.1) Right-Amiga-P - Open existing file by typing its name (7.2.2) Right-Amiga-[ - Open a new file (7.2.3) Right-Amiga-S - Save the current file (7.2.5) Right-Amiga-X - Cut selected text, save in clip area (7.3.1) Right-Amiga-C - Copy selected text into clip area (7.3.2) Right-Amiga-V - Paste clip area into file (7.3.3) Right-Amiga-F - Find string in any case (7.3.4.1) Right-Amiga-N - Find the next occurance of same string (7.3.4.2) Right-Amiga-R - Replace string with another (7.3.5.1) Right-Amiga-T - Find & replace same string again (7.3.5.2) Right-Amiga-L - Set text or next word to lower case (7.3.6.1) Right-Amiga-U - Set text or next word to upper case (7.3.6.2) Right-Amiga-K - Capitalize words or next word (7.3.6.3) Right-Amiga-G - Go to a specific line (7.3.7) Requester control... Right-Amiga-X - Clear text in string requester (8.2) Right-Amiga-Q - Restore original string requester text (8.2)